##Refactor attention visualizations into modular modules and add chord diagram support

Summary

This PR delivers a modular visualization architecture for attention analysis and introduces chord diagrams as a new visualization method.
Each visualization type is now separated into its own file, with shared data parsing centralized for reuse. This improves maintainability, extensibility, and clarity while keeping compatibility with existing OpenFold attention output files.

Linked Issue

Closes #7

Scope

Core architecture changes

• Separated visualization implementations into dedicated modules:
  • visualize_attention_arc_diagram_demo_utils.py
  • visualize_attention_3d_demo_utils.py
  • visualize_attention_head_heatmaps.py
  • visualize_attention_networks.py
  • visualize_attention_chord_diagrams.py (new)
• Added/standardized shared data loading and parsing in:
  • visualize_attention_data.py
• Updated dependent code paths to use shared parsing instead of duplicating logic.

New functionality

• Added Chord Diagram visualizations:
  • Per-head chord plots
  • Multi-head chord grid
  • Aggregated (all-head) chord plot
• Extended demo workflow to include chord generation.

Documentation and demo updates

• Updated docs and demo references to include modular visualization workflow and chord outputs.
• Updated sample output docs under:
  • examples/monomer/sample_attention_viz_outputs/README.md
  • docs/source/Head_Visualization_Heatmap_Network.md

Test coverage

• Added/updated tests for visualization data and chord behavior:
  • tests/test_visualize_attention_data.py
  • tests/test_visualize_attention_chord_diagrams.py

Why this change

• Modularity: Each visualization can now be developed, debugged, and reused independently.
• Maintainability: Shared parsing is centralized and no longer reimplemented across modules.
• Extensibility: New visualization types can be added with minimal impact on existing code.
• Interpretability: Chord diagrams provide an additional view for comparing residue-residue attention patterns across heads.

Functional impact

• No change to core OpenFold inference/model behavior.
• Visualization workflows are cleaner and easier to run method-by-method.
• Chord diagrams are now available in both demo and real-data workflows.

Testing and verification

A) Fastest end-to-end test (recommended)

The fastest and most reliable way to test all visualization updates is:

python scripts/run_head_heatmap_network_demo.py

This single command validates the entire pipeline:

• Shared parsing/loading (visualize_attention_data.py)
• Heatmap generation (visualize_attention_head_heatmaps.py)
• Network generation (visualize_attention_networks.py)
• Chord diagram generation (visualize_attention_chord_diagrams.py)
• End-to-end integration (scripts/run_head_heatmap_network_demo.py)

This is the recommended primary test, as it confirms all components work together.

B) Environment setup for reproducibility

If dependencies are not already installed:

python -m pip install matplotlib numpy scipy pandas biopython

Tested with Python 3.9+ on macOS/Linux environments.

C) Expected console output (successful run)

A successful run should print messages similar to:

Wrote synthetic MSA row attention: .../attention_files_6KWC_demo/msa_row_attn_layer47.txt
[Saved] Combined heatmaps: .../head_heatmaps/head_heatmaps_layer_47_6KWC.png
[Saved] Network: .../network_plots/network_layer_47_6KWC.png
[Saved] Per-head networks: .../network_plots/network_per_head_layer_47_6KWC.png
[Saved] Chord grid: .../chord_diagrams/chord_heads_layer_47_6KWC_grid.png
[Saved] Chord diagram: .../chord_diagrams/chord_aggregated_layer_47_6KWC.png

These confirm that each stage of the pipeline executed successfully.

D) Required artifact checks (file-level verification)

After running the demo, verify these files exist:

examples/monomer/sample_attention_viz_outputs/attention_files_6KWC_demo/msa_row_attn_layer47.txt
examples/monomer/sample_attention_viz_outputs/head_heatmaps/head_heatmaps_layer_47_6KWC.png
examples/monomer/sample_attention_viz_outputs/network_plots/network_layer_47_6KWC.png
examples/monomer/sample_attention_viz_outputs/network_plots/network_per_head_layer_47_6KWC.png
examples/monomer/sample_attention_viz_outputs/chord_diagrams/chord_heads_layer_47_6KWC_grid.png
examples/monomer/sample_attention_viz_outputs/chord_diagrams/chord_aggregated_layer_47_6KWC.png

Optional: Confirm per-head chord diagrams exist:
chord_head_0_layer_47_6KWC.png through chord_head_7_layer_47_6KWC.png

E) Visual sanity checks

Open generated images and verify:

• Heatmaps: multiple head subplots with non-empty intensity patterns (no blank panels)
• Network plots: visible residue nodes and weighted edges (aggregated + per-head views differ meaningfully)
• Chord diagrams:
  • Grid shows one circular plot per head
  • Individual heads differ visually
  • Aggregated diagram highlights strongest residue-residue interactions